Autogenerated HTML docs for v1.8.1-rc2-5-g252f9
diff --git a/gitweb.html b/gitweb.html index 7da525a..b8968a8 100644 --- a/gitweb.html +++ b/gitweb.html
@@ -2,15 +2,25 @@ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head> -<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> -<meta name="generator" content="AsciiDoc 8.5.2" /> +<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" /> +<meta name="generator" content="AsciiDoc 8.6.8" /> <title>gitweb(1)</title> <style type="text/css"> -/* Debug borders */ -p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 { -/* - border: 1px solid red; -*/ +/* Shared CSS for AsciiDoc xhtml11 and html5 backends */ + +/* Default font. */ +body { + font-family: Georgia,serif; +} + +/* Title font. */ +h1, h2, h3, h4, h5, h6, +div.title, caption.title, +thead, p.table.header, +#toctitle, +#author, #revnumber, #revdate, #revremark, +#footer { + font-family: Arial,Helvetica,sans-serif; } body { @@ -35,13 +45,8 @@ color: #083194; } -tt { - color: navy; -} - h1, h2, h3, h4, h5, h6 { color: #527bbd; - font-family: sans-serif; margin-top: 1.2em; margin-bottom: 0.5em; line-height: 1.3; @@ -59,9 +64,11 @@ h3 + * { clear: left; } +h5 { + font-size: 1.0em; +} div.sectionbody { - font-family: serif; margin-left: 0; } @@ -77,45 +84,48 @@ ul, ol, li > p { margin-top: 0; } +ul > li { color: #aaa; } +ul > li > * { color: black; } -pre { +.monospaced, code, pre { + font-family: "Courier New", Courier, monospace; + font-size: inherit; + color: navy; padding: 0; margin: 0; } -span#author { + +#author { color: #527bbd; - font-family: sans-serif; font-weight: bold; font-size: 1.1em; } -span#email { +#email { } -span#revnumber, span#revdate, span#revremark { - font-family: sans-serif; +#revnumber, #revdate, #revremark { } -div#footer { - font-family: sans-serif; +#footer { font-size: small; border-top: 2px solid silver; padding-top: 0.5em; margin-top: 4.0em; } -div#footer-text { +#footer-text { float: left; padding-bottom: 0.5em; } -div#footer-badges { +#footer-badges { float: right; padding-bottom: 0.5em; } -div#preamble { +#preamble { margin-top: 1.5em; margin-bottom: 1.5em; } -div.tableblock, div.imageblock, div.exampleblock, div.verseblock, +div.imageblock, div.exampleblock, div.verseblock, div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock, div.admonitionblock { margin-top: 1.0em; @@ -135,7 +145,6 @@ /* Block element titles. */ div.title, caption.title { color: #527bbd; - font-family: sans-serif; font-weight: bold; text-align: left; margin-top: 1.0em; @@ -157,13 +166,15 @@ div.sidebarblock > div.content { background: #ffffee; - border: 1px solid silver; + border: 1px solid #dddddd; + border-left: 4px solid #f0f0f0; padding: 0.5em; } div.listingblock > div.content { - border: 1px solid silver; - background: #f4f4f4; + border: 1px solid #dddddd; + border-left: 5px solid #f0f0f0; + background: #f8f8f8; padding: 0.5em; } @@ -171,8 +182,8 @@ padding-left: 1.0em; margin-left: 1.0em; margin-right: 10%; - border-left: 5px solid #dddddd; - color: #777777; + border-left: 5px solid #f0f0f0; + color: #888; } div.quoteblock > div.attribution { @@ -180,8 +191,9 @@ text-align: right; } -div.verseblock > div.content { - white-space: pre; +div.verseblock > pre.content { + font-family: inherit; + font-size: inherit; } div.verseblock > div.attribution { padding-top: 0.75em; @@ -254,35 +266,12 @@ margin-bottom: 0.1em; } -div.tableblock > table { - border: 3px solid #527bbd; -} -thead, p.table.header { - font-family: sans-serif; - font-weight: bold; -} tfoot { font-weight: bold; } td > div.verse { white-space: pre; } -p.table { - margin-top: 0; -} -/* Because the table frame attribute is overriden by CSS in most browsers. */ -div.tableblock > table[frame="void"] { - border-style: none; -} -div.tableblock > table[frame="hsides"] { - border-left-style: none; - border-right-style: none; -} -div.tableblock > table[frame="vsides"] { - border-top-style: none; - border-bottom-style: none; -} - div.hdlist { margin-top: 0.8em; @@ -339,25 +328,32 @@ min-width: 100px; } - -@media print { - div#footer-badges { display: none; } +div.colist td { + padding-right: 0.5em; + padding-bottom: 0.3em; + vertical-align: top; +} +div.colist td img { + margin-top: 0.3em; } -div#toc { +@media print { + #footer-badges { display: none; } +} + +#toc { margin-bottom: 2.5em; } -div#toctitle { +#toctitle { color: #527bbd; - font-family: sans-serif; font-size: 1.1em; font-weight: bold; margin-top: 1.0em; margin-bottom: 0.1em; } -div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 { +div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 { margin-top: 0; margin-bottom: 0; } @@ -373,69 +369,173 @@ margin-left: 6em; font-size: 0.9em; } -/* Overrides for manpage documents */ -h1 { + +span.aqua { color: aqua; } +span.black { color: black; } +span.blue { color: blue; } +span.fuchsia { color: fuchsia; } +span.gray { color: gray; } +span.green { color: green; } +span.lime { color: lime; } +span.maroon { color: maroon; } +span.navy { color: navy; } +span.olive { color: olive; } +span.purple { color: purple; } +span.red { color: red; } +span.silver { color: silver; } +span.teal { color: teal; } +span.white { color: white; } +span.yellow { color: yellow; } + +span.aqua-background { background: aqua; } +span.black-background { background: black; } +span.blue-background { background: blue; } +span.fuchsia-background { background: fuchsia; } +span.gray-background { background: gray; } +span.green-background { background: green; } +span.lime-background { background: lime; } +span.maroon-background { background: maroon; } +span.navy-background { background: navy; } +span.olive-background { background: olive; } +span.purple-background { background: purple; } +span.red-background { background: red; } +span.silver-background { background: silver; } +span.teal-background { background: teal; } +span.white-background { background: white; } +span.yellow-background { background: yellow; } + +span.big { font-size: 2em; } +span.small { font-size: 0.6em; } + +span.underline { text-decoration: underline; } +span.overline { text-decoration: overline; } +span.line-through { text-decoration: line-through; } + +div.unbreakable { page-break-inside: avoid; } + + +/* + * xhtml11 specific + * + * */ + +div.tableblock { + margin-top: 1.0em; + margin-bottom: 1.5em; +} +div.tableblock > table { + border: 3px solid #527bbd; +} +thead, p.table.header { + font-weight: bold; + color: #527bbd; +} +p.table { + margin-top: 0; +} +/* Because the table frame attribute is overriden by CSS in most browsers. */ +div.tableblock > table[frame="void"] { + border-style: none; +} +div.tableblock > table[frame="hsides"] { + border-left-style: none; + border-right-style: none; +} +div.tableblock > table[frame="vsides"] { + border-top-style: none; + border-bottom-style: none; +} + + +/* + * html5 specific + * + * */ + +table.tableblock { + margin-top: 1.0em; + margin-bottom: 1.5em; +} +thead, p.tableblock.header { + font-weight: bold; + color: #527bbd; +} +p.tableblock { + margin-top: 0; +} +table.tableblock { + border-width: 3px; + border-spacing: 0px; + border-style: solid; + border-color: #527bbd; + border-collapse: collapse; +} +th.tableblock, td.tableblock { + border-width: 1px; + padding: 4px; + border-style: solid; + border-color: #527bbd; +} + +table.tableblock.frame-topbot { + border-left-style: hidden; + border-right-style: hidden; +} +table.tableblock.frame-sides { + border-top-style: hidden; + border-bottom-style: hidden; +} +table.tableblock.frame-none { + border-style: hidden; +} + +th.tableblock.halign-left, td.tableblock.halign-left { + text-align: left; +} +th.tableblock.halign-center, td.tableblock.halign-center { + text-align: center; +} +th.tableblock.halign-right, td.tableblock.halign-right { + text-align: right; +} + +th.tableblock.valign-top, td.tableblock.valign-top { + vertical-align: top; +} +th.tableblock.valign-middle, td.tableblock.valign-middle { + vertical-align: middle; +} +th.tableblock.valign-bottom, td.tableblock.valign-bottom { + vertical-align: bottom; +} + + +/* + * manpage specific + * + * */ + +body.manpage h1 { padding-top: 0.5em; padding-bottom: 0.5em; border-top: 2px solid silver; border-bottom: 2px solid silver; } -h2 { +body.manpage h2 { border-style: none; } -div.sectionbody { - margin-left: 5%; +body.manpage div.sectionbody { + margin-left: 3em; } @media print { - div#toc { display: none; } + body.manpage div#toc { display: none; } } -/* Workarounds for IE6's broken and incomplete CSS2. */ -div.sidebar-content { - background: #ffffee; - border: 1px solid silver; - padding: 0.5em; -} -div.sidebar-title, div.image-title { - color: #527bbd; - font-family: sans-serif; - font-weight: bold; - margin-top: 0.0em; - margin-bottom: 0.5em; -} - -div.listingblock div.content { - border: 1px solid silver; - background: #f4f4f4; - padding: 0.5em; -} - -div.quoteblock-attribution { - padding-top: 0.5em; - text-align: right; -} - -div.verseblock-content { - white-space: pre; -} -div.verseblock-attribution { - padding-top: 0.75em; - text-align: left; -} - -div.exampleblock-content { - border-left: 3px solid #dddddd; - padding-left: 0.5em; -} - -/* IE6 sets dynamically generated links as visited. */ -div#toc a:visited { color: blue; } </style> <script type="text/javascript"> /*<+'])'); + var re = new RegExp('[hH]([1-'+(toclevels+1)+'])'); // Function that scans the DOM tree for header elements (the DOM2 // nodeIterator API would be a better technique but not supported by all // browsers). @@ -497,6 +597,25 @@ } var toc = document.getElementById("toc"); + if (!toc) { + return; + } + + // Delete existing TOC entries in case we're reloading the TOC. + var tocEntriesToRemove = []; + var i; + for (i = 0; i < toc.childNodes.length; i++) { + var entry = toc.childNodes[i]; + if (entry.nodeName.toLowerCase() == 'div' + && entry.getAttribute("class") + && entry.getAttribute("class").match(/^toclevel/)) + tocEntriesToRemove.push(entry); + } + for (i = 0; i < tocEntriesToRemove.length; i++) { + toc.removeChild(tocEntriesToRemove[i]); + } + + // Rebuild TOC entries. var entries = tocEntries(document.getElementById("content"), toclevels); for (var i = 0; i < entries.length; ++i) { var entry = entries[i]; @@ -524,24 +643,44 @@ */ footnotes: function () { - var cont = document.getElementById("content"); + // Delete existing footnote entries in case we're reloading the footnodes. + var i; var noteholder = document.getElementById("footnotes"); + if (!noteholder) { + return; + } + var entriesToRemove = []; + for (i = 0; i < noteholder.childNodes.length; i++) { + var entry = noteholder.childNodes[i]; + if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote") + entriesToRemove.push(entry); + } + for (i = 0; i < entriesToRemove.length; i++) { + noteholder.removeChild(entriesToRemove[i]); + } + + // Rebuild footnote entries. + var cont = document.getElementById("content"); var spans = cont.getElementsByTagName("span"); var refs = {}; var n = 0; for (i=0; i<spans.length; i++) { if (spans[i].className == "footnote") { n++; - // Use [\s\S] in place of . so multi-line matches work. - // Because JavaScript has no s (dotall) regex flag. - note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1]; + var note = spans[i].getAttribute("data-note"); + if (!note) { + // Use [\s\S] in place of . so multi-line matches work. + // Because JavaScript has no s (dotall) regex flag. + note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1]; + spans[i].innerHTML = + "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n + + "' title='View footnote' class='footnote'>" + n + "</a>]"; + spans[i].setAttribute("data-note", note); + } noteholder.innerHTML += "<div class='footnote' id='_footnote_" + n + "'>" + "<a href='#_footnoteref_" + n + "' title='Return to text'>" + n + "</a>. " + note + "</div>"; - spans[i].innerHTML = - "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n + - "' title='View footnote' class='footnote'>" + n + "</a>]"; var id =spans[i].getAttribute("id"); if (id != null) refs["#"+id] = n; } @@ -561,13 +700,36 @@ } } } +}, + +install: function(toclevels) { + var timerId; + + function reinstall() { + asciidoc.footnotes(); + if (toclevels) { + asciidoc.toc(toclevels); + } + } + + function reinstallAndRemoveTimer() { + clearInterval(timerId); + reinstall(); + } + + timerId = setInterval(reinstall, 500); + if (document.addEventListener) + document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false); + else + window.onload = reinstallAndRemoveTimer; } } +asciidoc.install(); /*]]>*/ </script> </head> -<body> +<body class="manpage"> <div id="header"> <h1> gitweb(1) Manual Page @@ -580,12 +742,15 @@ </div> </div> <div id="content"> +<div class="sect1"> <h2 id="_synopsis">SYNOPSIS</h2> <div class="sectionbody"> <div class="paragraph"><p>To get started with gitweb, run <a href="git-instaweb.html">git-instaweb(1)</a> from a git repository. This would configure and start your web server, and run web browser pointing to gitweb.</p></div> </div> +</div> +<div class="sect1"> <h2 id="_description">DESCRIPTION</h2> <div class="sectionbody"> <div class="paragraph"><p>Gitweb provides a web interface to git repositories. Its features include:</p></div> @@ -638,12 +803,15 @@ <a href="http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/">http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/</a> for gitweb source code, browsed using gitweb itself.</p></div> </div> +</div> +<div class="sect1"> <h2 id="_configuration">CONFIGURATION</h2> <div class="sectionbody"> <div class="paragraph"><p>Various aspects of gitweb’s behavior can be controlled through the configuration file <em>gitweb_config.perl</em> or <em>/etc/gitweb.conf</em>. See the <a href="gitweb.conf.html">gitweb.conf(5)</a> for details.</p></div> -<h3 id="_repositories">Repositories</h3><div style="clear:left"></div> +<div class="sect2"> +<h3 id="_repositories">Repositories</h3> <div class="paragraph"><p>Gitweb can show information from one or more Git repositories. These repositories have to be all on local filesystem, and have to share common repository root, i.e. be all under a single parent repository (but see also @@ -651,22 +819,24 @@ projects' root" subsection).</p></div> <div class="listingblock"> <div class="content"> -<pre><tt>our $projectroot = '/path/to/parent/directory';</tt></pre> +<pre><code>our $projectroot = '/path/to/parent/directory';</code></pre> </div></div> -<div class="paragraph"><p>The default value for <tt>$projectroot</tt> is <em>/pub/git</em>. You can change it during -building gitweb via <tt>GITWEB_PROJECTROOT</tt> build configuration variable.</p></div> -<div class="paragraph"><p>By default all git repositories under <tt>$projectroot</tt> are visible and available +<div class="paragraph"><p>The default value for <code>$projectroot</code> is <em>/pub/git</em>. You can change it during +building gitweb via <code>GITWEB_PROJECTROOT</code> build configuration variable.</p></div> +<div class="paragraph"><p>By default all git repositories under <code>$projectroot</code> are visible and available to gitweb. The list of projects is generated by default by scanning the -<tt>$projectroot</tt> directory for git repositories (for object databases to be +<code>$projectroot</code> directory for git repositories (for object databases to be more exact; gitweb is not interested in a working area, and is best suited to showing "bare" repositories).</p></div> -<div class="paragraph"><p>The name of the repository in gitweb is the path to its <tt>$GIT_DIR</tt> (its object -database) relative to <tt>$projectroot</tt>. Therefore the repository $repo can be +<div class="paragraph"><p>The name of the repository in gitweb is the path to its <code>$GIT_DIR</code> (its object +database) relative to <code>$projectroot</code>. Therefore the repository $repo can be found at "$projectroot/$repo".</p></div> -<h3 id="_projects_list_file_format">Projects list file format</h3><div style="clear:left"></div> +</div> +<div class="sect2"> +<h3 id="_projects_list_file_format">Projects list file format</h3> <div class="paragraph"><p>Instead of having gitweb find repositories by scanning filesystem starting from $projectroot, you can provide a pre-generated list of -visible projects by setting <tt>$projects_list</tt> to point to a plain text +visible projects by setting <code>$projects_list</code> to point to a plain text file with a list of projects (with some additional info).</p></div> <div class="paragraph"><p>This file uses the following format:</p></div> <div class="ulist"><ul> @@ -684,7 +854,7 @@ <li> <p> Whitespace separated fields; any run of whitespace can be used as field -separator (rules for Perl’s "<tt>split(" ", $line)</tt>"). +separator (rules for Perl’s "<code>split(" ", $line)</code>"). </p> </li> <li> @@ -709,7 +879,7 @@ </dt> <dd> <p> - path to repository GIT_DIR, relative to <tt>$projectroot</tt> + path to repository GIT_DIR, relative to <code>$projectroot</code> </p> </dd> <dt class="hdlist1"> @@ -730,31 +900,33 @@ <div class="paragraph"><p>Example contents:</p></div> <div class="listingblock"> <div class="content"> -<pre><tt>foo.git Joe+R+Hacker+<joe@example.com> -foo/bar.git O+W+Ner+<owner@example.org></tt></pre> +<pre><code>foo.git Joe+R+Hacker+<joe@example.com> +foo/bar.git O+W+Ner+<owner@example.org></code></pre> </div></div> <div class="paragraph"><p>By default this file controls only which projects are <strong>visible</strong> on projects list page (note that entries that do not point to correctly recognized git repositories won’t be displayed by gitweb). Even if a project is not visible on projects list page, you can view it nevertheless by hand-crafting -a gitweb URL. By setting <tt>$strict_export</tt> configuration variable (see +a gitweb URL. By setting <code>$strict_export</code> configuration variable (see <a href="gitweb.conf.html">gitweb.conf(5)</a>) to true value you can allow viewing only of repositories also shown on the overview page (i.e. only projects explicitly listed in projects list file will be accessible).</p></div> -<h3 id="_generating_projects_list_using_gitweb">Generating projects list using gitweb</h3><div style="clear:left"></div> +</div> +<div class="sect2"> +<h3 id="_generating_projects_list_using_gitweb">Generating projects list using gitweb</h3> <div class="paragraph"><p>We assume that GITWEB_CONFIG has its default Makefile value, namely <em>gitweb_config.perl</em>. Put the following in <em>gitweb_make_index.perl</em> file:</p></div> <div class="listingblock"> <div class="content"> -<pre><tt>read_config_file("gitweb_config.perl"); -$projects_list = $projectroot;</tt></pre> +<pre><code>read_config_file("gitweb_config.perl"); +$projects_list = $projectroot;</code></pre> </div></div> <div class="paragraph"><p>Then create the following script to get list of project in the format suitable for GITWEB_LIST build configuration variable (or -<tt>$projects_list</tt> variable in gitweb config):</p></div> +<code>$projects_list</code> variable in gitweb config):</p></div> <div class="listingblock"> <div class="content"> -<pre><tt>#!/bin/sh +<pre><code>#!/bin/sh export GITWEB_CONFIG="gitweb_make_index.perl" export GATEWAY_INTERFACE="CGI/1.1" @@ -762,13 +934,15 @@ export REQUEST_METHOD="GET" export QUERY_STRING="a=project_index" -perl -- /var/www/cgi-bin/gitweb.cgi</tt></pre> +perl -- /var/www/cgi-bin/gitweb.cgi</code></pre> </div></div> <div class="paragraph"><p>Run this script and save its output to a file. This file could then be used -as projects list file, which means that you can set <tt>$projects_list</tt> to its +as projects list file, which means that you can set <code>$projects_list</code> to its filename.</p></div> -<h3 id="_controlling_access_to_git_repositories">Controlling access to git repositories</h3><div style="clear:left"></div> -<div class="paragraph"><p>By default all git repositories under <tt>$projectroot</tt> are visible and +</div> +<div class="sect2"> +<h3 id="_controlling_access_to_git_repositories">Controlling access to git repositories</h3> +<div class="paragraph"><p>By default all git repositories under <code>$projectroot</code> are visible and available to gitweb. You can however configure how gitweb controls access to repositories.</p></div> <div class="ulist"><ul> @@ -776,28 +950,28 @@ <p> As described in "Projects list file format" section, you can control which projects are <strong>visible</strong> by selectively including repositories in projects -list file, and setting <tt>$projects_list</tt> gitweb configuration variable to -point to it. With <tt>$strict_export</tt> set, projects list file can be used to +list file, and setting <code>$projects_list</code> gitweb configuration variable to +point to it. With <code>$strict_export</code> set, projects list file can be used to control which repositories are <strong>available</strong> as well. </p> </li> <li> <p> You can configure gitweb to only list and allow viewing of the explicitly -exported repositories, via <tt>$export_ok</tt> variable in gitweb config file; see +exported repositories, via <code>$export_ok</code> variable in gitweb config file; see <a href="gitweb.conf.html">gitweb.conf(5)</a> manpage. If it evaluates to true, gitweb shows -repositories only if this file named by <tt>$export_ok</tt> exists in its object -database (if directory has the magic file named <tt>$export_ok</tt>). +repositories only if this file named by <code>$export_ok</code> exists in its object +database (if directory has the magic file named <code>$export_ok</code>). </p> -<div class="paragraph"><p>For example <a href="git-daemon.html">git-daemon(1)</a> by default (unless <tt>--export-all</tt> option +<div class="paragraph"><p>For example <a href="git-daemon.html">git-daemon(1)</a> by default (unless <code>--export-all</code> option is used) allows pulling only for those repositories that have <em>git-daemon-export-ok</em> file. Adding</p></div> <div class="listingblock"> <div class="content"> -<pre><tt>our $export_ok = "git-daemon-export-ok";</tt></pre> +<pre><code>our $export_ok = "git-daemon-export-ok";</code></pre> </div></div> <div class="paragraph"><p>makes gitweb show and allow access only to those repositories that can be -fetched from via <tt>git://</tt> protocol.</p></div> +fetched from via <code>git://</code> protocol.</p></div> </li> <li> <p> @@ -812,7 +986,7 @@ authorized to read the files:</p></div> <div class="listingblock"> <div class="content"> -<pre><tt>$export_auth_hook = sub { +<pre><code>$export_auth_hook = sub { use Apache2::SubRequest (); use Apache2::Const -compile => qw(HTTP_OK); my $path = "$_[0]/HEAD"; @@ -820,11 +994,13 @@ my $sub = $r->lookup_file($path); return $sub->filename eq $path && $sub->status == Apache2::Const::HTTP_OK; -};</tt></pre> +};</code></pre> </div></div> </li> </ul></div> -<h3 id="_per_repository_gitweb_configuration">Per-repository gitweb configuration</h3><div style="clear:left"></div> +</div> +<div class="sect2"> +<h3 id="_per_repository_gitweb_configuration">Per-repository gitweb configuration</h3> <div class="paragraph"><p>You can configure individual repositories shown in gitweb by creating file in the <em>GIT_DIR</em> of git repository, or by setting some repo configuration variable (in <em>GIT_DIR/config</em>, see <a href="git-config.html">git-config(1)</a>).</p></div> @@ -836,59 +1012,59 @@ <dd> <p> A html file (HTML fragment) which is included on the gitweb project - "summary" page inside <tt><div></tt> block element. You can use it for longer + "summary" page inside <code><div></code> block element. You can use it for longer description of a project, to provide links (for example to project’s homepage), etc. This is recognized only if XSS prevention is off - (<tt>$prevent_xss</tt> is false, see <a href="gitweb.conf.html">gitweb.conf(5)</a>); a way to include + (<code>$prevent_xss</code> is false, see <a href="gitweb.conf.html">gitweb.conf(5)</a>); a way to include a README safely when XSS prevention is on may be worked out in the future. </p> </dd> <dt class="hdlist1"> -description (or <tt>gitweb.description</tt>) +description (or <code>gitweb.description</code>) </dt> <dd> <p> - Short (shortened to <tt>$projects_list_description_width</tt> in the projects + Short (shortened to <code>$projects_list_description_width</code> in the projects list page, which is 25 characters by default; see <a href="gitweb.conf.html">gitweb.conf(5)</a>) single line description of a project (of a repository). Plain text file; HTML will be escaped. By default set to </p> <div class="listingblock"> <div class="content"> -<pre><tt>Unnamed repository; edit this file to name it for gitweb.</tt></pre> +<pre><code>Unnamed repository; edit this file to name it for gitweb.</code></pre> </div></div> <div class="paragraph"><p>from the template during repository creation, usually installed in -<em>/usr/share/git-core/templates/</em>. You can use the <tt>gitweb.description</tt> repo +<em>/usr/share/git-core/templates/</em>. You can use the <code>gitweb.description</code> repo configuration variable, but the file takes precedence.</p></div> </dd> <dt class="hdlist1"> -category (or <tt>gitweb.category</tt>) +category (or <code>gitweb.category</code>) </dt> <dd> <p> Singe line category of a project, used to group projects if - <tt>$projects_list_group_categories</tt> is enabled. By default (file and + <code>$projects_list_group_categories</code> is enabled. By default (file and configuration variable absent), uncategorized projects are put in the - <tt>$project_list_default_category</tt> category. You can use the - <tt>gitweb.category</tt> repo configuration variable, but the file takes + <code>$project_list_default_category</code> category. You can use the + <code>gitweb.category</code> repo configuration variable, but the file takes precedence. </p> -<div class="paragraph"><p>The configuration variables <tt>$projects_list_group_categories</tt> and -<tt>$project_list_default_category</tt> are described in <a href="gitweb.conf.html">gitweb.conf(5)</a></p></div> +<div class="paragraph"><p>The configuration variables <code>$projects_list_group_categories</code> and +<code>$project_list_default_category</code> are described in <a href="gitweb.conf.html">gitweb.conf(5)</a></p></div> </dd> <dt class="hdlist1"> -cloneurl (or multiple-valued <tt>gitweb.url</tt>) +cloneurl (or multiple-valued <code>gitweb.url</code>) </dt> <dd> <p> File with repository URL (used for clone and fetch), one per line. Displayed in the project summary page. You can use multiple-valued - <tt>gitweb.url</tt> repository configuration variable for that, but the file + <code>gitweb.url</code> repository configuration variable for that, but the file takes precedence. </p> <div class="paragraph"><p>This is per-repository enhancement / version of global prefix-based -<tt>@git_base_url_list</tt> gitweb configuration variable (see +<code>@git_base_url_list</code> gitweb configuration variable (see <a href="gitweb.conf.html">gitweb.conf(5)</a>).</p></div> </dd> <dt class="hdlist1"> @@ -896,27 +1072,30 @@ </dt> <dd> <p> - You can use the <tt>gitweb.owner</tt> repository configuration variable to set + You can use the <code>gitweb.owner</code> repository configuration variable to set repository’s owner. It is displayed in the project list and summary page. </p> <div class="paragraph"><p>If it’s not set, filesystem directory’s owner is used (via GECOS field, -i.e. real name field from <strong>getpwuid</strong>(3)) if <tt>$projects_list</tt> is unset -(gitweb scans <tt>$projectroot</tt> for repositories); if <tt>$projects_list</tt> +i.e. real name field from <strong>getpwuid</strong>(3)) if <code>$projects_list</code> is unset +(gitweb scans <code>$projectroot</code> for repositories); if <code>$projects_list</code> points to file with list of repositories, then project owner defaults to value from this file for given repository.</p></div> </dd> <dt class="hdlist1"> -various <tt>gitweb.*</tt> config variables (in config) +various <code>gitweb.*</code> config variables (in config) </dt> <dd> <p> - Read description of <tt>%feature</tt> hash for detailed list, and descriptions. + Read description of <code>%feature</code> hash for detailed list, and descriptions. See also "Configuring gitweb features" section in <a href="gitweb.conf.html">gitweb.conf(5)</a> </p> </dd> </dl></div> </div> +</div> +</div> +<div class="sect1"> <h2 id="_actions_and_urls">ACTIONS, AND URLS</h2> <div class="sectionbody"> <div class="paragraph"><p>Gitweb can use path_info (component) based URLs, or it can pass all necessary @@ -924,7 +1103,7 @@ five components:</p></div> <div class="listingblock"> <div class="content"> -<pre><tt>.../gitweb.cgi/<repo>/<action>/<revision>:/<path>?<arguments></tt></pre> +<pre><code>.../gitweb.cgi/<repo>/<action>/<revision>:/<path>?<arguments></code></pre> </div></div> <div class="dlist"><dl> <dt class="hdlist1"> @@ -977,7 +1156,7 @@ looks like this:</p></div> <div class="listingblock"> <div class="content"> -<pre><tt>.../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments></tt></pre> +<pre><code>.../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments></code></pre> </div></div> <div class="paragraph"><p>Each action is implemented as a subroutine, and must be present in %actions hash. Some actions are disabled by default, and must be turned on via feature @@ -985,9 +1164,10 @@ configuration file:</p></div> <div class="listingblock"> <div class="content"> -<pre><tt>$feature{'blame'}{'default'} = [1];</tt></pre> +<pre><code>$feature{'blame'}{'default'} = [1];</code></pre> </div></div> -<h3 id="_actions">Actions:</h3><div style="clear:left"></div> +<div class="sect2"> +<h3 id="_actions">Actions:</h3> <div class="paragraph"><p>The standard actions are:</p></div> <div class="dlist"><dl> <dt class="hdlist1"> @@ -1140,34 +1320,40 @@ </dd> </dl></div> </div> +</div> +</div> +<div class="sect1"> <h2 id="_webserver_configuration">WEBSERVER CONFIGURATION</h2> <div class="sectionbody"> <div class="paragraph"><p>This section explains how to configure some common webservers to run gitweb. In -all cases, <tt>/path/to/gitweb</tt> in the examples is the directory you ran installed -gitweb in, and contains <tt>gitweb_config.perl</tt>.</p></div> +all cases, <code>/path/to/gitweb</code> in the examples is the directory you ran installed +gitweb in, and contains <code>gitweb_config.perl</code>.</p></div> <div class="paragraph"><p>If you’ve configured a web server that isn’t listed here for gitweb, please send in the instructions so they can be included in a future release.</p></div> -<h3 id="_apache_as_cgi">Apache as CGI</h3><div style="clear:left"></div> +<div class="sect2"> +<h3 id="_apache_as_cgi">Apache as CGI</h3> <div class="paragraph"><p>Apache must be configured to support CGI scripts in the directory in which gitweb is installed. Let’s assume that it is <em>/var/www/cgi-bin</em> directory.</p></div> <div class="listingblock"> <div class="content"> -<pre><tt>ScriptAlias /cgi-bin/ "/var/www/cgi-bin/" +<pre><code>ScriptAlias /cgi-bin/ "/var/www/cgi-bin/" <Directory "/var/www/cgi-bin"> Options Indexes FollowSymlinks ExecCGI AllowOverride None Order allow,deny Allow from all -</Directory></tt></pre> +</Directory></code></pre> </div></div> <div class="paragraph"><p>With that configuration the full path to browse repositories would be:</p></div> <div class="literalblock"> <div class="content"> -<pre><tt>http://server/cgi-bin/gitweb.cgi</tt></pre> +<pre><code>http://server/cgi-bin/gitweb.cgi</code></pre> </div></div> -<h3 id="_apache_with_mod_perl_via_modperl_registry">Apache with mod_perl, via ModPerl::Registry</h3><div style="clear:left"></div> +</div> +<div class="sect2"> +<h3 id="_apache_with_mod_perl_via_modperl_registry">Apache with mod_perl, via ModPerl::Registry</h3> <div class="paragraph"><p>You can use mod_perl with gitweb. You must install Apache::Registry (for mod_perl 1.x) or ModPerl::Registry (for mod_perl 2.x) to enable this support.</p></div> @@ -1175,7 +1361,7 @@ Apache configuration (for mod_perl 2.x) is suitable.</p></div> <div class="listingblock"> <div class="content"> -<pre><tt>Alias /perl "/var/www/perl" +<pre><code>Alias /perl "/var/www/perl" <Directory "/var/www/perl"> SetHandler perl-script @@ -1185,44 +1371,50 @@ AllowOverride None Order allow,deny Allow from all -</Directory></tt></pre> +</Directory></code></pre> </div></div> <div class="paragraph"><p>With that configuration the full path to browse repositories would be:</p></div> <div class="literalblock"> <div class="content"> -<pre><tt>http://server/perl/gitweb.cgi</tt></pre> +<pre><code>http://server/perl/gitweb.cgi</code></pre> </div></div> -<h3 id="_apache_with_fastcgi">Apache with FastCGI</h3><div style="clear:left"></div> +</div> +<div class="sect2"> +<h3 id="_apache_with_fastcgi">Apache with FastCGI</h3> <div class="paragraph"><p>Gitweb works with Apache and FastCGI. First you need to rename, copy or symlink gitweb.cgi to gitweb.fcgi. Let’s assume that gitweb is installed in <em>/usr/share/gitweb</em> directory. The following Apache configuration is suitable (UNTESTED!)</p></div> <div class="listingblock"> <div class="content"> -<pre><tt>FastCgiServer /usr/share/gitweb/gitweb.cgi +<pre><code>FastCgiServer /usr/share/gitweb/gitweb.cgi ScriptAlias /gitweb /usr/share/gitweb/gitweb.cgi Alias /gitweb/static /usr/share/gitweb/static <Directory /usr/share/gitweb/static> SetHandler default-handler -</Directory></tt></pre> +</Directory></code></pre> </div></div> <div class="paragraph"><p>With that configuration the full path to browse repositories would be:</p></div> <div class="literalblock"> <div class="content"> -<pre><tt>http://server/gitweb</tt></pre> +<pre><code>http://server/gitweb</code></pre> </div></div> </div> +</div> +</div> +<div class="sect1"> <h2 id="_advanced_web_server_setup">ADVANCED WEB SERVER SETUP</h2> <div class="sectionbody"> -<div class="paragraph"><p>All of those examples use request rewriting, and need <tt>mod_rewrite</tt> +<div class="paragraph"><p>All of those examples use request rewriting, and need <code>mod_rewrite</code> (or equivalent; examples below are written for Apache).</p></div> -<h3 id="_single_url_for_gitweb_and_for_fetching">Single URL for gitweb and for fetching</h3><div style="clear:left"></div> -<div class="paragraph"><p>If you want to have one URL for both gitweb and your <tt>http://</tt> +<div class="sect2"> +<h3 id="_single_url_for_gitweb_and_for_fetching">Single URL for gitweb and for fetching</h3> +<div class="paragraph"><p>If you want to have one URL for both gitweb and your <code>http://</code> repositories, you can configure Apache like this:</p></div> <div class="listingblock"> <div class="content"> -<pre><tt><VirtualHost *:80> +<pre><code><VirtualHost *:80> ServerName git.example.org DocumentRoot /pub/git SetEnv GITWEB_CONFIG /etc/gitweb.conf @@ -1236,14 +1428,14 @@ # make access for "dumb clients" work RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \ /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] -</VirtualHost></tt></pre> +</VirtualHost></code></pre> </div></div> <div class="paragraph"><p>The above configuration expects your public repositories to live under -<em>/pub/git</em> and will serve them as <tt>http://git.domain.org/dir-under-pub-git</tt>, +<em>/pub/git</em> and will serve them as <code>http://git.domain.org/dir-under-pub-git</code>, both as cloneable GIT URL and as browseable gitweb interface. If you then -start your <a href="git-daemon.html">git-daemon(1)</a> with <tt>--base-path=/pub/git --export-all</tt> -then you can even use the <tt>git://</tt> URL with exactly the same path.</p></div> -<div class="paragraph"><p>Setting the environment variable <tt>GITWEB_CONFIG</tt> will tell gitweb to use the +start your <a href="git-daemon.html">git-daemon(1)</a> with <code>--base-path=/pub/git --export-all</code> +then you can even use the <code>git://</code> URL with exactly the same path.</p></div> +<div class="paragraph"><p>Setting the environment variable <code>GITWEB_CONFIG</code> will tell gitweb to use the named file (i.e. in this example <em>/etc/gitweb.conf</em>) as a configuration for gitweb. You don’t really need it in above example; it is required only if your configuration file is in different place than built-in (during @@ -1255,21 +1447,23 @@ (<em>/etc/gitweb.conf</em> following example):</p></div> <div class="listingblock"> <div class="content"> -<pre><tt>@stylesheets = ("/some/absolute/path/gitweb.css"); +<pre><code>@stylesheets = ("/some/absolute/path/gitweb.css"); $my_uri = "/"; $home_link = "/"; -$per_request_config = 1;</tt></pre> +$per_request_config = 1;</code></pre> </div></div> <div class="paragraph"><p>Nowadays though gitweb should create HTML base tag when needed (to set base URI for relative links), so it should work automatically.</p></div> -<h3 id="_webserver_configuration_with_multiple_projects_root">Webserver configuration with multiple projects' root</h3><div style="clear:left"></div> +</div> +<div class="sect2"> +<h3 id="_webserver_configuration_with_multiple_projects_root">Webserver configuration with multiple projects' root</h3> <div class="paragraph"><p>If you want to use gitweb with several project roots you can edit your Apache virtual host and gitweb configuration files in the following way.</p></div> <div class="paragraph"><p>The virtual host configuration (in Apache configuration file) should look like this:</p></div> <div class="listingblock"> <div class="content"> -<pre><tt><VirtualHost *:80> +<pre><code><VirtualHost *:80> ServerName git.example.org DocumentRoot /pub/git SetEnv GITWEB_CONFIG /etc/gitweb.conf @@ -1302,24 +1496,24 @@ # make access for "dumb clients" work RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \ /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] -</VirtualHost></tt></pre> +</VirtualHost></code></pre> </div></div> -<div class="paragraph"><p>Here actual project root is passed to gitweb via <tt>GITWEB_PROJECT_ROOT</tt> +<div class="paragraph"><p>Here actual project root is passed to gitweb via <code>GITWEB_PROJECT_ROOT</code> environment variable from a web server, so you need to put the following line in gitweb configuration file (<em>/etc/gitweb.conf</em> in above example):</p></div> <div class="listingblock"> <div class="content"> -<pre><tt>$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";</tt></pre> +<pre><code>$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";</code></pre> </div></div> <div class="paragraph"><p><strong>Note</strong> that this requires to be set for each request, so either -<tt>$per_request_config</tt> must be false, or the above must be put in code -referenced by <tt>$per_request_config</tt>;</p></div> -<div class="paragraph"><p>These configurations enable two things. First, each unix user (<tt><user></tt>) of +<code>$per_request_config</code> must be false, or the above must be put in code +referenced by <code>$per_request_config</code>;</p></div> +<div class="paragraph"><p>These configurations enable two things. First, each unix user (<code><user></code>) of the server will be able to browse through gitweb git repositories found in <em>~/public_git/</em> with the following url:</p></div> <div class="literalblock"> <div class="content"> -<pre><tt>http://git.example.org/~<user>/</tt></pre> +<pre><code>http://git.example.org/~<user>/</code></pre> </div></div> <div class="paragraph"><p>If you do not want this feature on your server just remove the second rewrite rule.</p></div> @@ -1327,20 +1521,22 @@ use the '~’ as first character, just comment or remove the second rewrite rule, and uncomment one of the following according to what you want.</p></div> <div class="paragraph"><p>Second, repositories found in <em>/pub/scm/</em> and <em>/var/git/</em> will be accessible -through <tt>http://git.example.org/scm/</tt> and <tt>http://git.example.org/var/</tt>. +through <code>http://git.example.org/scm/</code> and <code>http://git.example.org/var/</code>. You can add as many project roots as you want by adding rewrite rules like the third and the fourth.</p></div> -<h3 id="_path_info_usage">PATH_INFO usage</h3><div style="clear:left"></div> +</div> +<div class="sect2"> +<h3 id="_path_info_usage">PATH_INFO usage</h3> <div class="paragraph"><p>If you enable PATH_INFO usage in gitweb by putting</p></div> <div class="listingblock"> <div class="content"> -<pre><tt>$feature{'pathinfo'}{'default'} = [1];</tt></pre> +<pre><code>$feature{'pathinfo'}{'default'} = [1];</code></pre> </div></div> <div class="paragraph"><p>in your gitweb configuration file, it is possible to set up your server so that it consumes and produces URLs in the form</p></div> <div class="literalblock"> <div class="content"> -<pre><tt>http://git.example.com/project.git/shortlog/sometag</tt></pre> +<pre><code>http://git.example.com/project.git/shortlog/sometag</code></pre> </div></div> <div class="paragraph"><p>i.e. without <em>gitweb.cgi</em> part, by using a configuration such as the following. This configuration assumes that <em>/var/www/gitweb</em> is the @@ -1348,7 +1544,7 @@ complementary static files (stylesheet, favicon, JavaScript):</p></div> <div class="listingblock"> <div class="content"> -<pre><tt><VirtualHost *:80> +<pre><code><VirtualHost *:80> ServerAlias git.example.com DocumentRoot /var/www/gitweb @@ -1364,13 +1560,13 @@ RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^.* /gitweb.cgi/$0 [L,PT] </Directory> -</VirtualHost></tt></pre> +</VirtualHost></code></pre> </div></div> <div class="paragraph"><p>The rewrite rule guarantees that existing static files will be properly served, whereas any other URL will be passed to gitweb as PATH_INFO parameter.</p></div> <div class="paragraph"><p><strong>Notice</strong> that in this case you don’t need special settings for -<tt>@stylesheets</tt>, <tt>$my_uri</tt> and <tt>$home_link</tt>, but you lose "dumb client" +<code>@stylesheets</code>, <code>$my_uri</code> and <code>$home_link</code>, but you lose "dumb client" access to your project .git dirs (described in "Single URL for gitweb and for fetching" section). A possible workaround for the latter is the following: in your project root dir (e.g. <em>/pub/git</em>) have the projects @@ -1378,7 +1574,7 @@ <em>/pub/git/project.git</em>) and configure Apache as follows:</p></div> <div class="listingblock"> <div class="content"> -<pre><tt><VirtualHost *:80> +<pre><code><VirtualHost *:80> ServerAlias git.example.com DocumentRoot /var/www/gitweb @@ -1395,43 +1591,51 @@ RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^.* /gitweb.cgi/$0 [L,PT] </Directory> -</VirtualHost></tt></pre> +</VirtualHost></code></pre> </div></div> <div class="paragraph"><p>The additional AliasMatch makes it so that</p></div> <div class="literalblock"> <div class="content"> -<pre><tt>http://git.example.com/project.git</tt></pre> +<pre><code>http://git.example.com/project.git</code></pre> </div></div> <div class="paragraph"><p>will give raw access to the project’s git dir (so that the project can be cloned), while</p></div> <div class="literalblock"> <div class="content"> -<pre><tt>http://git.example.com/project</tt></pre> +<pre><code>http://git.example.com/project</code></pre> </div></div> <div class="paragraph"><p>will provide human-friendly gitweb access.</p></div> <div class="paragraph"><p>This solution is not 100% bulletproof, in the sense that if some project has a named ref (branch, tag) starting with <em>git/</em>, then paths such as</p></div> <div class="literalblock"> <div class="content"> -<pre><tt>http://git.example.com/project/command/abranch..git/abranch</tt></pre> +<pre><code>http://git.example.com/project/command/abranch..git/abranch</code></pre> </div></div> <div class="paragraph"><p>will fail with a 404 error.</p></div> </div> +</div> +</div> +<div class="sect1"> <h2 id="_bugs">BUGS</h2> <div class="sectionbody"> <div class="paragraph"><p>Please report any bugs or feature requests to <a href="mailto:git@vger.kernel.org">git@vger.kernel.org</a>, putting "gitweb" in the subject of email.</p></div> </div> +</div> +<div class="sect1"> <h2 id="_see_also">SEE ALSO</h2> <div class="sectionbody"> <div class="paragraph"><p><a href="gitweb.conf.html">gitweb.conf(5)</a>, <a href="git-instaweb.html">git-instaweb(1)</a></p></div> <div class="paragraph"><p><em>gitweb/README</em>, <em>gitweb/INSTALL</em></p></div> </div> +</div> +<div class="sect1"> <h2 id="_git">GIT</h2> <div class="sectionbody"> <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div> </div> </div> +</div> <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> 